home *** CD-ROM | disk | FTP | other *** search
/ AGA Toolkit '97 / The AGA Toolkit '97.iso / programming / c / projectman211 / sascprojectman.doc < prev    next >
Encoding:
Text File  |  1996-09-07  |  14.4 KB  |  329 lines
  1.                          SASCProjectManager
  2.                          ==================
  3.  
  4.                     ©1993,1994,1995 Donald Milne
  5.  
  6.  
  7. Please see the readme file for important copyright information.
  8.  
  9. This is v2.11 of a project manager for SAS/C v6.0 or greater. It is
  10. freely distributable within the limits given in the readme file.
  11.  
  12. Introduction
  13. ------------
  14.  
  15. This is a front end to simplify maintenance and building of SAS/C
  16. projects, particularly those with multiple source files and headers.
  17. It allows the user to construct a list of source files that make up
  18. the project and to define global and local compiler options for these
  19. files. It can also build a list of #includ'ed local headers (those
  20. in "...") and use all this information to construct a make file.
  21.  
  22. The user can compile individual files, link the project, build the
  23. project via smake, set global compiler and linker options and set
  24. local compiler options on a file by file basis. The user can also
  25. edit both source files (.c/.cpp/.cxx/.cc/.s/.a/.asm) and header files.
  26.  
  27. The makefile that the program consructs ensures that any changes to
  28. the source files, local headers, local options and global options will
  29. result in the recompilation and relinking of all affected parts of the
  30. source code.
  31.  
  32. Installation
  33. ------------
  34.  
  35. 1) Copy 'SASCProjectManager' to SC:C/.
  36. 2) Delete the SC:Starter_Project drawer.
  37. 3) Copy the supplied Starter_Project drawer to SC:
  38. 4) Ensure the line 'C:Assign C: SC:C ADD' is in your user-startup.
  39.  
  40. When the SCSetUp program is used to create a new project, the files
  41. in the new Starter_Project drawer will be used. The Build, Edit and
  42. SCoptions icons are replaced with the ProjectMan icon.
  43.  
  44. Using The Program
  45. -----------------
  46.  
  47. Double click on the ProjectMan icon. A window will appear with a large
  48. scrolling list and several buttons. Create your source files using the
  49. 'Operation/Edit New File...' menu item. Once you have at least one source
  50. file you can select Project/Add Item... (Amiga A) and a file requester
  51. will appear. Use this to select a source file and click OK. The file will
  52. be added to the scrolling list. The file requester supports multi-selection
  53. of files using the shift key.
  54.  
  55. Another alternative is to drag the icon(s) for the file(s) into the
  56. ProjectMan window as the window is an AppWindow and supports drag and
  57. drop of icons.
  58.  
  59. Note that only files matching '#?.c', '#?.(s|a|asm) or '#?.(cpp|cxx|cc)'
  60. will be displayed in the file requester and the AppWindow will ignore
  61. any file dropped in it that fails to match one of these patterns.
  62.  
  63. Note that '.a', '.asm' and '.s' assembler files are now supported (as of
  64. v2.3b) and are passed to 'asm' via the 'sc' frontend so the global/local
  65. options will apply.
  66.  
  67. When you are ready to compile, select Operation/Global Options...
  68. (Amiga G). This will run the normal SCOpts program and allow you to
  69. set the options that all source files will be compiled and linked with.
  70. Next select the source file you wish to compile from the list then
  71. click on the Compile button. A window will open in which the compiler
  72. output will be displayed. When the compiler is finished, close the
  73. window using its close gadget.
  74.  
  75. Use the Make button to recompile and relink all files that require it,
  76. using smake and will construct a smakefile if one does not exist.
  77.  
  78. Use the Link button to relink all object files.
  79.  
  80. Use the Build button to recompile and relink all files whether it is
  81. required or not, a requester will prompt you before comencing with this
  82. operation. If you do not have a real-time clock then you should use this
  83. option the first time you do a compile in order to set the correct
  84. datestamps on the object files and the executable.
  85.  
  86. The Show Headers button will scan the selected file and display a list
  87. of all files that are #include'ed in "..." in a scrolling list in a
  88. seperate window. Click on Done to return to the main window. Note that
  89. only the source file will be searched, any files it #include's will not
  90. be searched so header files should not #include any non-system headers
  91. of their own. (System headers in <...> are ok however as these are not
  92. scanned for). The Edit button can be used to edit (using the editor
  93. selected by the user in the EDITOR tooltype) the currently selected
  94. header file.
  95. This also handles INCLUDE'ed '.i' files, names in single quotes (') are
  96. assumed to be header files and are ignored, names in double quotes (")
  97. are taken to be user include files and will be listed.
  98. The file search can take some time, particularly for larger files, to
  99. speed things up, put the comment /* END INC */ (the spaces are needed)
  100. after all the includes to stop the search at that point.
  101.  
  102. The Local Options button runs the SCOpts program and allows the setting
  103. of options local to source file. The source file must be selected before
  104. clicking on this button. If the source file is an assembler file and you
  105. have specified another assembler via the ASMCMD tooltype then a window
  106. will pop up containing a string gadget enabling you to edit the options
  107. passed to your assembler on the command line.
  108.  
  109. The Edit Files button allows the editing (using the editor selected by
  110. the user in the EDITOR tooltype) of the currently selected source file.
  111. This is also achieved by double clicking on the file in the listview.
  112.  
  113. The /\ and \/ buttons move the currently selected item in the
  114. listview in that direction allowing the user to arrange the files
  115. as they wish.
  116.  
  117. The Operation menu has entries that perform the same actions as these
  118. buttons as well as an entry for 'Global Options...' (Amiga-G), 'Edit New
  119. File...' (Amiga N), 'Remake...' (Amiga-R) and 'Compile & Link...'
  120. (Amiga-/).
  121. The 'remake' option does the same as make but always rebuilds the
  122. smakefile first, use this if you add new source or header files or
  123. add/delete a local options file.
  124. The 'compile & link' optiion compiles the currently selected source
  125. file then performs a link operation.
  126.  
  127. The Project menu has the add item entry but also has a 'Delete Item...'
  128. entry (Amiga D) to remove source files from the list (it does not
  129. actually delete the source file itself however), an 'About...' item which
  130. does the same as in any other program, an 'Iconify' entry (Amiga I) which
  131. reduces the window to an AppIcon on the workbench (double click on it to
  132. get the window back) and a 'Quit...' option (Amiga Q) which performs the
  133. same action as the window close gadget.
  134.  
  135. Gadget Keyboard Equivalents
  136. ---------------------------
  137.  
  138. Main Window :
  139.   Edit File      'e'
  140.   Show Headers   'h'
  141.   Local Options  'o'
  142.   Compile        'c'
  143.   Link           'l'
  144.   Build          'b'
  145.   Make           'm'
  146.   Move Up (/\)   'u'
  147.   Move Down (\/) 'd'
  148.   Listview       'f' & 'F'
  149. Show Headers Window :
  150.   Edit     'e'
  151.   Done     'd'
  152.   Listview 'f' & 'F'
  153. Edit Options Window :
  154.   String Gadget  'a'
  155.   OK             'o'
  156.   Cancel         'c'
  157.  
  158. Note : The listview keyboard equivalents are available in V39+ only.
  159.  
  160. Notes
  161. -----
  162.  
  163. The program creates several files.
  164.  
  165. ProjectMan - this is the data file assosciated with the icon and it
  166.              contains the source file list and the window x and y
  167.              positions (as of v2.6).
  168.  
  169. GLOBALOPTS - this is the global options file.
  170.  
  171. <sourcefile>.lopt - this is the local options file assosiated with a
  172.                     source file, either an scoptions style file or
  173.                     a single line with the command line arguments
  174.                     for the assembler.
  175.  
  176. smakefile - the created makefile passed to smake.
  177.  
  178. <projectname>.lnk - the command file passed by sc to slink.
  179.  
  180. The SCOpts program creates an SCOptions file but this is renamed to
  181. either GLOBALOPTS or <sourcefile>.lopt by this program.
  182.  
  183. Because of the way SCOpts works, not all options will be overidden
  184. when using local options, it is not possible to turn off the optimizer
  185. locally for instance, if you need to have part of your source
  186. compilled without the optimizer, turn it off in global options and
  187. turn it on in the relevant local options. This will hold for other
  188. on/off options (debugging for instance) as well.
  189.  
  190. It is also recommended that you give the project a name in the global
  191. options to avoid problems, If the project is not given a name, it will
  192. be named after the first source file in the list and if this changes
  193. then the compiler etc may become confused (not to mention that you will
  194. get multiple copies of your executable and '.lnk' files).
  195.  
  196. IMPORTANT - Only ever run SASCProjectManager from the supplied project
  197. icon, never give it a tool icon and run it from workbench. It should
  198. also not be run from the CLI. As of v2.4, it should not be possible to
  199. run SASCProjectManager by any other means.
  200.  
  201. Using Another Assembler
  202. -----------------------
  203.  
  204. The assembler must be runnable from the CLI and capable of taking its
  205. options as command line arguments. The command will take the form of
  206. 'assembler_command' 'options' 'file_name' and therefore the assembler
  207. must accept this form of command line. If the assembler needs an option
  208. before the file name (such as 'from') then put that at the end of the
  209. option string (ie '-iINCLUDE: -l from').
  210.  
  211. Tool Types
  212. ----------
  213. EDITOR : Set the full path to the users prefered editor (defaults to
  214.          sc:c/se if not present).
  215. WINX   : Set the initial x position of the main window (defaults to 20).
  216.          As of v2.6, this only sets the iconified window x position as
  217.          the actual window position is saved in the ProjectMan file.
  218. WINY   : Set the initial y position of the main window (defaults to 20).
  219.          As of v2.6, this only sets the iconified window y position as
  220.          the actual window position is saved in the ProjectMan file.
  221. HEIGHT : Set the inner height of the window, the listview height is set
  222.          proportional to this (defaults to 88).
  223. OPCON  : Sets the output console window size and position using the
  224.          conventional console specification - the format is very
  225.          important 'x/y/w/h', eg OPCON=0/40/640/100.
  226.          (defaults to 0/20/640/180).
  227. CONDEV : Sets the output console device, eg 'CON:' or 'KCON:'.
  228.          (defaults to CON:).
  229. ASMCMD : Sets the assembler to be used (needs full path if not in C:)
  230.          for .asm, .a or .s files. (defaults to SC for the SAS assembler
  231.          via the sc front-end).
  232.  
  233. Release Notes
  234. -------------
  235. v2.11  Really fixed startup enforcer hits (honest). Cleared up an error
  236.        in the double-click handling.
  237. v2.10a Fixed enforcer hits on startup (finally).
  238. v2.10  New menu options 'Remake' (works the same way make used to, make
  239.        itself now only builds a smakefile if there isn't one) and
  240.        'Compile & Link' to compile a single source file and relink.
  241. v2.9a  Oops! Make now works again!
  242. v2.9   Added tooltype to set the console device to be used for the output
  243.        window. Added tooltype to set the assembler to be used for .asm,
  244.        .s or .a files. LocalOpts button will produce a text edit window
  245.        for assembly files if another assembler is specified. Should also
  246.        now handle lower and upper case file names properly.
  247. v2.8b  More minor bug fixes (can now make without a GLOBALOPTS file).
  248. v2.8a  Minor bug fixes.
  249. v2.8   Added facility to delete local options. Added facility to speed
  250.        up header file search using '/* END INC */' string embedded in
  251.        the code. Now displays busy pointer whilst performing the
  252.        header file search.
  253. v2.7   The output console window size and position can now be specified
  254.        using the OPCON tooltype. The main window now opens in its saved
  255.        position rather than opening in its default position and then
  256.        moving to the saved position. The minimum window size is now 88
  257.        and not 100.
  258. v2.6a  The height option in v2.6 introduced a few problems with the
  259.        iconification handlers which are fixed in this version.
  260. v2.6   Now saves window position with ProjectMan file. WINX and WINY
  261.        are overridden by the saved position but can be used to set the
  262.        position of the iconified window. A new tool-type, HEIGHT, sets
  263.        the height of the window and hence of the listview.
  264. v2.5c  Added '.asm', '.cxx' and '.cc' to allowed file patterns.
  265. v2.5b  Minor bug fixes.
  266. v2.5a  Modified linking and  making so there is no need to run sc to
  267.        get slink to work properly. By placing SC:C in the C: assign, the
  268.        problems with paths and workbench can be avoided and sc will be
  269.        able to find slink itself. This also means that asm can be kept
  270.        in sc:c aswell.
  271. v2.5   Added gadget keyboard equivalents.
  272. v2.4c  More minor bug fixes, ASL file requester should now accept
  273.        assembly .s and .a files, smakefile improvements, etc.
  274. v2.4b  Minor bug fixes.
  275. v2.4a  The 'Make' option now produces a better smakefile. This should
  276.        sort some problems with large projects. Other minor bug fixes
  277.        to sort out the new batch that v2.4 introduced.
  278. v2.4   Added selectable editor and initial position tooltypes, ability
  279.        to move source items in the list, support for assembler include
  280.        files, project name in the window title and double click on
  281.        listview item to edit.
  282. v2.3b  More minor fixes - Thanks to Scott Johnston for the suggestions.
  283.        Now supports '.a' and '.s' files via the 'sc' frontend.
  284.        Newlook menus under OS3.0 or later added.
  285.        Fixed bug with pathnames to files being ignored.
  286. v2.3a  Minor fixes, build puts up a requester again and the wait pointer
  287.        will be the preferences busy pointer under v39+. Also will now
  288.        only run under v37 (it always did but running it on an earlier
  289.        OS would not be caught - until it crashed).
  290. v2.3   Minor bug fixes, addition of zoom gadget and persistent output
  291.        window.
  292. v2.2   Added edit files facility. (first release)
  293. v2.1   Added 'iconify' option. (not released)
  294. v2.0   Added multi-file selection and AppWindow support. (not released)
  295. v1.2   Original version. (not released)
  296.  
  297. Archive Contents
  298. ----------------
  299.  
  300. ProjectMan.info
  301. ProjectMan/Starter_Project.info
  302. ProjectMan/Starter_Project/Debug
  303. ProjectMan/Starter_Project/Debug.info
  304. ProjectMan/Starter_Project/Find.info
  305. ProjectMan/Starter_Project/ProjectMan
  306. ProjectMan/Starter_Project/ProjectMan.info
  307. ProjectMan/README                            (distribution notes)
  308. ProjectMan/README.info
  309. ProjectMan/SASCProjectMan.doc                (this file)
  310. ProjectMan/SASCProjectMan.doc.info
  311. ProjectMan/SASCProjectManager                (the program)
  312.  
  313. Contact Details
  314. ---------------
  315.  
  316. You can contact me by mailing 'donald' on the Alpha Complex BBS on
  317. 01224-626203 (UK).
  318.  
  319. Thanks
  320. ------
  321.  
  322. Thanks to :
  323.     Commodore-Amiga for the machine.
  324.     SAS Institute for the compiler.
  325.     Alex for Alpha Complex and Wintermute.
  326.     Gary Girvan for the suggestions and bug finding.
  327.     Scott Johnston for the wishlist.
  328.     Norman Baccari for helping with enforcer problems.
  329.